fix: scope Stop hook to active workflow only by aireilly · Pull Request #139 · redhat-documentation/redhat-docs-agent-tools

aireilly · 2026-05-01T10:01:31Z

Summary

The Stop hook previously scanned all progress files and blocked Claude from stopping when any stale in_progress workflow existed — even from previous sessions or different tickets. This caused Claude to hijack sessions and work on tickets the user didn't ask about
Introduces an active-workflow marker (.claude/docs/.active-workflow) that the orchestrator writes when starting/resuming a workflow. The hook now reads only this marker, ignoring all other progress files
Stale/malformed markers are auto-cleaned when they point to missing or completed workflows

Test plan

Verify stale in_progress workflows from previous sessions no longer trigger the hook (no .active-workflow marker → hook exits 0)
Start a new workflow with /docs-orchestrator TICKET-1 — verify .active-workflow is created and hook blocks correctly mid-workflow
Start a second workflow for a different ticket — verify the marker is overwritten and the hook only blocks for the new ticket
Complete a workflow — verify the marker is deleted and the hook allows stop
Test anti-loop guard: block 5 times → 6th stop attempt succeeds and marker is cleaned up

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation
- Added docs for an “active workflow” marker file that tracks the currently running workflow and its stop/resume behavior.
Refactor
- Stop checks now consult a single active-workflow marker and focus step evaluation on that workflow; resume/start overwrite the marker.
Bug Fixes
- Marker is removed on completion, failure, or when stale to prevent spurious stop blocking; stop-counter scoped to the active workflow.
Chores
- Plugin version bumped.

The Stop hook scanned all progress files and blocked Claude from stopping when any stale in_progress workflow existed — even from previous sessions or for different tickets. This caused Claude to hijack sessions and work on tickets the user didn't ask about. Introduce an active-workflow marker (.claude/docs/.active-workflow) that the orchestrator writes when starting or resuming a workflow. The hook now reads only this marker, ignoring all other progress files. Stale markers are auto-cleaned when they point to missing or completed workflows. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED

coderabbitai · 2026-05-01T10:01:42Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 99aee09d-195c-4e11-ad23-3b9499808383

📥 Commits

Reviewing files that changed from the base of the PR and between c70c763 and 37abd30.

📒 Files selected for processing (2)

plugins/docs-tools/.claude-plugin/plugin.json
plugins/docs-tools/skills/docs-orchestrator/SKILL.md

Walkthrough

Adds a single active-workflow sidecar at .claude/docs/.active-workflow that the orchestrator writes/overwrites on create/resume/update. The Stop hook reads this marker to scope blocking checks, deletes it when stale or on terminal outcomes, and exits non-zero on marker parse failure.

Changes

Cohort / File(s)	Summary
Orchestrator docs `plugins/docs-tools/skills/docs-orchestrator/SKILL.md`	Documents the `.claude/docs/.active-workflow` sidecar, when it is created/overwritten (create, resume, update), required fields (`progress_file`, `ticket`, `workflow_type`), and deletion behavior on terminal outcomes and edge cases.
Stop hook `plugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.sh`	Refactors stop-hook to use a single active-workflow marker. Validates/parses marker (jq failures => exit 2), treats missing/stale/absent referenced progress file as non-blocking (cleanup + exit 0), scopes stop_count/step evaluation to the referenced progress file, blocks only when `.status == "in_progress"` and incomplete steps + stop_count < threshold, and cleans up marker and counter on terminal conditions.
Plugin manifest `plugins/docs-tools/.claude-plugin/plugin.json`	Bumps plugin `version` from `0.0.61` → `0.0.62`.

Sequence Diagram(s)

sequenceDiagram
    participant Orchestrator
    participant Marker as ".claude/docs/.active-workflow"
    participant StopHook
    participant Progress as "progress.json"

    Orchestrator->>Marker: write/update marker (progress_file, ticket, workflow_type)
    Note over Marker: marker represents current active workflow
    StopHook->>Marker: read marker
    alt marker missing
        StopHook->>StopHook: exit 0 (allow stop)
    else marker present
        StopHook->>StopHook: parse marker (jq)
        alt parse failure
            StopHook->>StopHook: print error, exit 2
        else parse success
            StopHook->>Progress: read referenced progress_file
            alt progress file missing or marker stale
                StopHook->>Marker: delete marker
                StopHook->>StopHook: exit 0
            else progress read
                alt progress.status == "in_progress"
                    StopHook->>Progress: evaluate step_order/steps and stop_count
                    alt incomplete steps remain AND stop_count < threshold
                        StopHook->>StopHook: emit stderr, exit 2 (block stop)
                    else
                        StopHook->>Marker: remove marker
                        StopHook->>StopHook: exit 0
                    end
                else
                    StopHook->>Marker: remove marker
                    StopHook->>StopHook: exit 0
                end
            end
        end
    end

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

Add Stop hook settings to prevent premature workflow termination #83: Modifies the same stop-hook and related behavior; directly related to active-workflow marker changes.
fix: scope Stop hook to active workflow only #139: Also updates orchestrator docs and stop-hook to rely on .claude/docs/.active-workflow; strongly connected to this change.

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error, 1 inconclusive)

Check name	Status	Explanation	Resolution
Plugin Registry Consistency	❌ Error	The PR modified plugin.json version from 0.0.57 to 0.0.58, but marketplace.json was not updated to reflect this version change.	Update marketplace.json docs-tools entry version from 0.0.57 to 0.0.58 to maintain registry consistency with plugin.json.
Skill And Script Conventions	❓ Inconclusive	The files referenced in the PR cannot be located in the repository for inspection.	Verify repository population and provide access to the modified files for compliance verification.

✅ Passed checks (8 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: scoping the Stop hook to only the active workflow, which is the core fix across all modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
No Real People Names In Style References	✅ Passed	Examined all modified files (SKILL.md, workflow-completion-check.sh, plugin.json) and found no references to real people names in style references or any context.
Git Safety Rules	✅ Passed	The pull request does not introduce any Git Safety Rule violations. The modified files contain no git push, git fetch, hardcoded remote names, or force push operations.
No Untrusted Mcp Servers	✅ Passed	The pull request introduces no MCP server installations. Modified files contain documentation, bash implementation, and version bump with no external dependencies.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch fix/scope-stop-hook-to-active-workflow

_{Review rate limit: 9/10 reviews remaining, refill in 6 minutes.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

github-actions · 2026-05-01T10:01:55Z

🚀 Deployed on https://69f523818cd86f7adf48bb98--redhat-docs-agent-tools.netlify.app

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In
`@plugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.sh`:
- Around line 31-38: The hook currently suppresses jq errors and treats parse
failures as stale state, then deletes the MARKER; change this so PROGRESS_FILE
and TICKET are parsed with jq but you check jq's exit status and do not remove
MARKER on parse errors. Concretely, in workflow-completion-check.sh capture jq's
exit code when reading PROGRESS_FILE and TICKET (references: PROGRESS_FILE,
TICKET, MARKER), and if jq returns non-zero (parse/read failure) exit non-zero
(fail closed) without running rm -f "$MARKER"; only when jq succeeds and both
variables are empty should you remove the marker and exit 0.

In `@plugins/docs-tools/skills/docs-orchestrator/SKILL.md`:
- Around line 337-345: Update the JSON example so the progress_file uses the
lowercased ticket placeholder to match the directory rule: change the path in
progress_file (and the filename token) to use <ticket-lower> (e.g.
".claude/docs/<ticket-lower>/workflow/<workflow-type>_<ticket-lower>.json");
ensure you update the progress_file value and any occurrence of the ticket
placeholder in that example so it consistently references <ticket-lower>
alongside the existing <workflow-type> token.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 7ebc2c26-ef2b-4675-b68d-03ca2db782a9

📥 Commits

Reviewing files that changed from the base of the PR and between 4c571f6 and dceeef7.

📒 Files selected for processing (2)

plugins/docs-tools/skills/docs-orchestrator/SKILL.md
plugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.sh

… path Stop hook now checks jq exit status when parsing .active-workflow marker. Parse failures block stop (exit 2) instead of silently deleting the marker. Also aligns the SKILL.md progress_file example with the lowercase ticket directory convention. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED

chore: bump docs-tools plugin version to 0.0.58

710fbc9

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED

coderabbitai Bot reviewed May 1, 2026

View reviewed changes

Comment thread plugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.sh Outdated

Comment thread plugins/docs-tools/skills/docs-orchestrator/SKILL.md

aireilly and others added 2 commits May 1, 2026 11:21

Merge branch 'main' into fix/scope-stop-hook-to-active-workflow

37abd30

aireilly merged commit 8cdba22 into main May 1, 2026
5 of 6 checks passed

coderabbitai Bot mentioned this pull request May 1, 2026

refactor: move workflow workspace from .claude/ to .agent_workspace/ #142

Merged

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: scope Stop hook to active workflow only#139

fix: scope Stop hook to active workflow only#139
aireilly merged 4 commits intomainfrom
fix/scope-stop-hook-to-active-workflow

aireilly commented May 1, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented May 1, 2026 •

edited

Loading

Review failed

Pre-merge checks failed

Uh oh!

github-actions Bot commented May 1, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

aireilly commented May 1, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Pre-merge checks failed

❌ Failed checks (1 error, 1 inconclusive)

Uh oh!

github-actions Bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

aireilly commented May 1, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 1, 2026 •

edited

Loading

github-actions Bot commented May 1, 2026 •

edited

Loading